Cargo Registration

1. Overview

The Cargo Registration doctype in the VSD Fleet MS module is used to register and manage cargo transport operations. It captures customer details, cargo information, transport modes, related trips, and enables direct invoicing based on cargo movement and billing configuration.

This doctype is a central piece in the cargo logistics workflow, bridging between cargo entry, fund requests, and sales invoicing.

2. Key Features

Customer Selection: Choose the customer for whom cargo is being registered.
Cargo Details Table: Add cargo line items with:
- Transporter type (In House or Sub-Contractor)
- Truck and driver details
- Route and trip references
- Billing method (weight-based or flat)
- Rate, UOM, and service item
Invoicing Button: "Create Invoice" button to generate a Sales Invoice.
Fund Linkage: Link the cargo registration to requested funds.
Transport Type: Specify internal or cross-border movement.
Automatic Dimension Setting: Sets cost centers and other dimensions automatically.

3. Pre-Requisites

Customer records must exist.
Service Items should be set up with correct UOMs and pricing.
Truck, Driver, and Route master data should be configured.
Sales Invoice doctype must be active.
set_dimension utility must be defined in vsd_fleet_ms.utils.dimension.

4. Step-by-Step Usage

a) Creating a New Cargo Registration

Go to VSD Fleet MS > Cargo Registration.
Click New.
Fill in:
- Customer
- Posting Date
- Company
- Transport Type
In the Cargo Details table:
- Select Transporter Type
- If In House, choose Assigned Truck and optional Trip
- If Sub-Contractor, enter Truck Number and Driver Name
- Provide Service Item, Rate, UOM, and Net Weight if applicable
- Choose Cargo Route

b) Linking Requested Funds

Use the Requested Fund Details table to link relevant fund requests.

c) Generating a Sales Invoice

Click the Create Invoice button.
System will:
- Create a Sales Invoice
- Link invoice to cargo rows
- Show a success message with invoice number

5. Script Customizations

Backend (Python)

In cargo_registration.py:

@frappe.whitelist()
def create_sales_invoice(doc, rows):
    # Accepts JSON doc and rows, builds items,
    # sets dimensions, creates and inserts Sales Invoice

Handles flat or weight-based billing
Sets item descriptions (truck, driver, trip, route)
Applies dimension settings using set_dimension

Frontend (JavaScript)

In cargo_registration.js:

frappe.ui.form.on('Cargo Registration', {
    create_invoice: function(frm) {
        // Gathers selected rows and calls create_sales_invoice
    }
});

6. Troubleshooting (Common Errors and Resolutions)

Error	Cause	Resolution
Service Item not found	Missing `service_item`	Ensure each cargo row includes a valid item
Net Weight required	`allow_bill_on_weight` is checked	Enter a value in `net_weight_tonne`
No invoice generated	No rows selected or incomplete data	Verify selected rows have complete data
Dimension error	`set_dimension` utility missing or broken	Ensure utility is correctly implemented

7. User Roles and Permissions

Role	Permissions
Fleet Manager	Full access to Cargo Registration
Accounts User	View Sales Invoices
System Manager	Full access and configuration control

Permissions can be managed using Role Permission Manager.

8. Key Notes

Naming Series: CRG0-REG-.YYYY.-.####
Trip and transport logic differs for In House and Sub-Contractors
Automatically updates invoice field in child table after creation
Dimensions are applied to each item row using set_dimension

9. What Business Process Pain Point Does It Help Remove

The Cargo Registration doctype helps eliminate manual, error-prone cargo and billing workflows by:

Automatically creating sales invoices from transport data
Simplifying cargo tracking across internal and subcontracted moves
Linking fund requests, trips, and billing for accountability
Reducing revenue leakages and enhancing operational visibility

Fleet ms